home *** CD-ROM | disk | FTP | other *** search
/ Magnum One / Magnum One (Mid-American Digital) (Disc Manufacturing).iso / d13 / devdvr.arc / DRIVER.ASM < prev    next >
Assembly Source File  |  1986-09-01  |  18KB  |  629 lines
  1. 4
  2. Capture Buffer Transfer
  3. No error detection/correction
  4.  
  5. Opening capture buffer...
  6.         name    driver
  7.         page    55,132
  8.         title   'DRIVER --- installable driver template'
  9.  
  10. ;
  11. ; This is a "template" for a MS-DOS installable device driver.
  12. ; The actual driver subroutines are stubs only and have
  13. ; no effect but to return a non-error "done" status.
  14. ; 
  15. ; Ray Duncan
  16. ; Laboratory Microsystems Inc.
  17. ; April 1985
  18.  
  19. code    segment public 'CODE'
  20.  
  21. driver  proc    far
  22.  
  23.         assume  cs:code,ds:code,es:code
  24.  
  25.         org     0
  26.  
  27.  
  28. Max_Cmd equ     15              ; MS-DOS command code maximum
  29.                                 ; this is 15 for MS-DOS 3.x
  30.                                 ; and 12 for MS-DOS 2.x 
  31.  
  32.  
  33. cr      equ     0dh             ; ASCII carriage return
  34. lf      equ     0ah             ; ASCII line feed
  35. eom     equ     '$'             ; end of message signal
  36.  
  37.  
  38.         page
  39. ;
  40. ; Device Driver Header
  41. ;
  42. Header  dd      -1              ;link to next device,-1= end of list
  43.  
  44.         dw      8000h           ;attribute word
  45.                                 ;bit 15=1 for character devices
  46.  
  47.         dw      Strat           ;device "Strategy" entry point
  48.  
  49.         dw      Intr            ;device "Interrupt" entry point
  50.  
  51.         db      'DRIVER  '      ;char device name, 8 char, or
  52.                                 ;if block device, no. of units
  53.                                 ;in first byte followed by 
  54.                                 ;7 don't care bytes     
  55.  
  56.  
  57.  
  58. ; Interpretation of Attribute word:
  59. ; 
  60. ; Bit           Significance
  61. ;
  62. ; 15            =1 for character drivers
  63. ; 14            =1 if driver can handle IOCTL
  64. ; 13            =1 if block device & non-IBM format
  65. ; 12            0
  66. ; 11            open/close/RM supported (DOS 3.x)
  67. ; 10            0
  68. ;  9            0
  69. ;  8            0
  70. ;  7            0
  71. ;  6            0
  72. ;  5            0
  73. ;  4            0
  74. ;  3            =1 if CLOCK device
  75. ;  2            =1 if NUL device
  76. ;  1            =1 if Standard Output
  77. ;  0            =1 if Standard Input
  78.  
  79.         page
  80. ;
  81. ; local variables for use by driver
  82. ;
  83. RH_Ptr  dd      ?               ; pointer to request header
  84.                                 ; passed to Strat by BDOS
  85.  
  86. Ident   db      cr,lf,lf
  87.         db      'LMI Example Device Driver 1.0'
  88.         db      cr,lf
  89.         db      'Copyright (c) 1985 '
  90.         db      'Laboratory Microsystems Inc.' 
  91.         db      cr,lf,lf,eom
  92. ;
  93. ; MS-DOS Command Codes dispatch table.
  94. ; The "Interrupt" routine uses this table and the 
  95. ; Command Code supplied in the Request Header to 
  96. ; transfer to the appropriate driver subroutine.
  97.  
  98. Dispatch:
  99.         dw      Init            ;  0 = init driver into system
  100.         dw      Media_Chk       ;  1 = media check on blk dev
  101.         dw      Build_Bpb       ;  2 = build BIOS param block
  102.         dw      Ioctl_Inp       ;  3 = I/O ctrl read from dev
  103.         dw      Input           ;  4 = normal destructive read
  104.         dw      Nd_Input        ;  5 = non-destructive read,no wait
  105.         dw      Inp_Stat        ;  6 = return current input status
  106.         dw      Inp_Flush       ;  7 = flush device input buffers
  107.         dw      Output          ;  8 = normal output to device
  108.         dw      Outp_Vfy        ;  9 = output with verify
  109.         dw      Outp_Stat       ; 10 = return current output status
  110.         dw      Outp_Flush      ; 11 = flush output buffers
  111.         dw      Ioctl_Outp      ; 12 = I/O control output
  112.         dw      Dev_Open        ; 13 = device open      (MS-DOS 3.x)
  113.         dw      Dev_Close       ; 14 = device close     (MS-DOS 3.x)
  114.         dw      Rem_Media       ; 15 = removeable media (MS-DOS 3.x)
  115.         page
  116. ; 
  117. ; MS-DOS Request Header structure definition
  118. ;
  119. ; The first 13 bytes of all Request Headers are the same
  120. ; and are referred to as the "Static" part of the Header.
  121. ; The number and meaning of the following bytes varies.
  122. ; In this "Struc" definition we show the Request Header
  123. ; contents for Read and Write calls.
  124. ;
  125. Request struc                   ; request header template structure
  126.         
  127.                                 ; beginning of "Static" portion
  128. Rlength db      ?               ; length of request header
  129. Unit    db      ?               ; unit number for this request
  130. Command db      ?               ; request header's command code
  131. Status  dw      ?               ; driver's return status word
  132. Reserve db      8 dup (?)       ; reserved area
  133.                                 ; end of "Static" portion       
  134.  
  135. Media   db      ?               ; media descriptor byte
  136. Address dd      ?               ; memory address for transfer
  137. Count   dw      ?               ; byte/sector count value
  138. Sector  dw      ?               ; starting sector value
  139.  
  140. Request ends                    ; end of request header template
  141.  
  142. ;
  143. ; Status word is interpreted as follows:
  144. ;
  145. ;  Bit(s)   Significance
  146. ;   15       Error
  147. ;   10-14    Reserved
  148. ;   9        Busy
  149. ;   8        Done
  150. ;   0-7      Error code if bit 15=1
  151.  
  152. ; Predefined BDOS error codes are:
  153. ; 
  154. ;   0       Write protect violation
  155. ;   1       Unknown unit
  156. ;   2       Drive not ready
  157. ;   3       Unknown command
  158. ;   4       CRC error
  159. ;   5       Bad drive request structure length
  160. ;   6       Seek error
  161. ;   7       Unknown media
  162. ;   8       Sector not found
  163. ;   9       Printer out of paper
  164. ;   10      Write fault
  165. ;   11      Read fault
  166. ;   12      General failure     
  167. ;   13-14   Reserved
  168. ;   15      Invalid disk change  (MS-DOS 3.x)
  169.  
  170.         page
  171.  
  172. ; Device Driver "Strategy Routine"
  173.  
  174. ; Each time a request is made for this device, the BDOS
  175. ; first calls "Strategy routine",  then immediately calls
  176. ; the "Interrupt routine".  
  177.  
  178. ; The Strategy routine is passed the address of the
  179. ; Request Header in ES:BX, which it saves in a local
  180. ; variable and then returns to the BDOS.
  181.  
  182. Strat   proc    far     
  183.                                 ; save address of Request Header
  184.         mov     word ptr cs:[RH_Ptr],bx
  185.         mov     word ptr cs:[RH_Ptr+2],es
  186.  
  187.         ret                     ; back to BDOS
  188.  
  189. Strat   endp
  190.  
  191.         page
  192.  
  193.  
  194. ; Device Driver "Interrupt Routine"
  195.  
  196. ; This entry point is called by the BDOS immediately after 
  197. ; the call to the "Strategy Routine", which saved the long
  198. ; address of the Request Header in the local variable "RH_Ptr".
  199.  
  200. ; The "Interrupt Routine" uses the Command Code passed in
  201. ; the Request Header to transfer to the appropriate device
  202. ; handling routine.  Each command code routine is responsible
  203. ; for any necessary return information into the Request Header,
  204. ; then transfers to Error or Exit to set the Return Status code.
  205.  
  206. Intr    proc  far
  207.  
  208.         push    ax              ; save general registers 
  209.         push    bx
  210.         push    cx
  211.         push    dx
  212.         push    ds
  213.         push    es
  214.         push    di
  215.         push    si
  216.         push    bp
  217.  
  218.         push    cs              ; make local data addressable
  219.         pop     ds
  220.  
  221.         les     di,[RH_Ptr]     ; ES:DI = Request Header
  222.  
  223.                                 ; get BX = Command Code
  224.         mov     bl,es:[di.Command]
  225.         xor     bh,bh
  226.         cmp     bx,Max_Cmd      ; make sure its legal
  227.         jg      Unk_Command     ; too big, exit with error code
  228.         shl     bx,1            ; form index to Dispatch table
  229.                                 ; and branch to driver routine
  230.         jmp     word ptr [bx+Dispatch]
  231.  
  232.         page
  233.  
  234.  
  235. ; General collection of exit points for the driver routines.
  236.  
  237.  
  238. Unk_Command:                    ; Come here if Command Code too big.
  239.         mov     al,3            ; Sets "Unknown Command" error 
  240.                                 ; code and "Done" bit.
  241.  
  242. Error:                          ; Transfer here with AL = error code.
  243.         mov     ah,81h          ; Sets "Error" and "Done" bits.
  244.         jmp     Exit
  245.  
  246. Done:   mov     ah,1            ; Come here if I/O complete and
  247.                                 ; no error, sets "Done" bit only.
  248.  
  249.  
  250. Exit:                           ; General purpose exit point.
  251.                                 ; Transfer here with AX = 
  252.                                 ; Return Status word to be
  253.                                 ; placed into Request Header.
  254.  
  255.         lds     bx,cs:[RH_Ptr]          ; set status
  256.         mov     ds:[bx.Status],ax
  257.  
  258.         pop     bp              ;restore general registers
  259.         pop     si
  260.         pop     di
  261.         pop     es
  262.         pop     ds
  263.         pop     dx
  264.         pop     cx
  265.         pop     bx
  266.         pop     ax
  267.         ret                     ; back to BDOS
  268.  
  269.         page
  270.  
  271.  
  272. ; Function 1  Media Check
  273.  
  274. ; Block devices only.  Should be a NOP for character devices.
  275. ;
  276. ; This routine is called first by BDOS for a block device transfer,
  277. ; passing current media descriptor byte at Request Header + 
  278. ;
  279. ; Media Check routine sets status word and in addition passes back 
  280. ; return byte at Request Header + 14  as follows:
  281.  
  282. ;    -1  Media has been changed
  283. ;     0  Don't know if media changed
  284. ;     1  Media has not been changed
  285. ;
  286. ; If driver can return 1 or -1, performance is improved because
  287. ; MS-DOS does not need to reread the FAT for each directory access.
  288.  
  289.  
  290. Media_Chk:
  291.  
  292.         jmp     Done
  293.  
  294.         page
  295.  
  296. ;
  297. ; Function 2  Build BIOS Parameter Block
  298. ; 
  299. ; Block devices only.  Should be a NOP for character devices.
  300. ;
  301. ; This routine is called by MS-DOS when Media-Changed code is
  302. ; returned by Media Check routine, or if Not Sure code is returned
  303. ; and there are no dirty buffers.
  304. ; 
  305. ; Build BPB call receives pointer to one-sector buffer in Address
  306. ; Field of Request Header (offset 14).  If "Non-IBM-Format" bit 
  307. ; in attribute word is zero, the buffer contains the first sector
  308. ; of the FAT including the media identification byte and should not 
  309. ; be altered by the driver.   If the "Non-IBM-Format" bit is set, 
  310. ; the buffer may be used as scratch space.
  311. ;
  312. ; The Build BPB routine sets status and returns a DWORD pointer to 
  313. ; the new Bios Parameter Block at Request Header + 18.
  314. ;
  315.  
  316. Build_Bpb:
  317.  
  318.         jmp     Done
  319.  
  320.         page
  321.  
  322. ;
  323. ; Function 3  I/O Control Read 
  324. ; 
  325. ; Only called if IOCTL bit set in Device Header Attribute word.
  326. ;
  327. ; Called with:
  328. ;
  329. ; Request Header + 13  BYTE   Media descriptor byte from DPB
  330. ; Request Header + 14  DWORD  Transfer address
  331. ; Request Header + 18  WORD   byte/sector count
  332. ; Request Header + 20  WORD   starting sector no. (block dev.)
  333. ;
  334. ; Returns the Return Status word set appropriately, and
  335. ; Request Header + 18  WORD   actual bytes or sectors transferred
  336. ; 
  337. ; No error check is performed on IOCTL I/O calls.
  338.  
  339. Ioctl_Inp:
  340.  
  341.         jmp     Done
  342.  
  343.         page
  344.  
  345. ;
  346. ; Function 4  Read from Device
  347. ;
  348. ; Called with
  349. ;
  350. ; Request Header + 13  BYTE   Media descriptor byte from DPB
  351. ; Request Header + 14  DWORD  Transfer address
  352. ; Request Header + 18  WORD   byte/sector count
  353. ; Request Header + 20  WORD   starting sector no. (block dev.)
  354. ;
  355. ; Returns the Return Status word set appropriately, and
  356. ; Request Header + 18  WORD   actual bytes or sectors transferred
  357.  
  358. Input: 
  359.  
  360.         jmp     Done
  361.  
  362.         page
  363.  
  364. ;
  365. ; Function 5  Non-destructive Read from Device
  366. ; 
  367. ; Character devices only.
  368. ;
  369. ; If Input Status request returns Busy bit=0 (characters 
  370. ; waiting), ; the next character that would be read is returned 
  371. ; at Request Header + 13.  This character is not removed from
  372. ; the Input Buffer.  This basically provides the capability to 
  373. ; "look-ahead" by one character.
  374.  
  375. Nd_Input:
  376.  
  377.         jmp     Done
  378.  
  379.         page
  380.  
  381. ;
  382. ; Function 6  Input Status
  383. ; 
  384. ; Character devices only.
  385. ;
  386. ; Sets the Returned Status word:
  387. ; Done bit = 1
  388. ; Busy bit = 1 read request would go to physical device
  389. ;          = 0 characters already in device buffer, read request
  390. ;              would return quickly.
  391. ;
  392. ; MS-DOS assumes all character devices have type-ahead buffer.
  393. ; If device does not have type-ahead buffer, should always
  394. ; return Busy bit=0 so MS-DOS will not hang.
  395.  
  396. Inp_Stat:
  397.  
  398.         jmp     Done
  399.  
  400.         page
  401.  
  402. ;
  403. ; Function 7  Flush Input Buffers
  404. ; 
  405. ; Character devices only.
  406. ;
  407. ; Terminate all pending requests, i.e. the Input buffer is
  408. ; emptied.
  409.  
  410. Inp_Flush:
  411.  
  412.         jmp     Done
  413.  
  414.         page
  415.  
  416. ;
  417. ; Function 8  Write to Device
  418. ; 
  419. ; Called with
  420. ;
  421. ; Request Header + 13  BYTE   Media descriptor byte from DPB
  422. ; Request Header + 14  DWORD  Transfer address
  423. ; Request Header + 18  WORD   byte/sector count
  424. ; Request Header + 20  WORD   starting sector no. (block dev.)
  425. ;
  426. ; Returns the Return Status word set appropriately, and
  427. ; Request Header + 18  WORD   actual bytes or sectors transferred
  428.  
  429. Output: 
  430.  
  431.         jmp     Done
  432.  
  433.         page
  434.  
  435. ;
  436. ; Function 9  Write with Verify to Device
  437. ; 
  438. ; Called with
  439. ;
  440. ; Request Header + 13  BYTE   Media descriptor byte from DPB
  441. ; Request Header + 14  DWORD  Transfer address
  442. ; Request Header + 18  WORD   byte/sector count
  443. ; Request Header + 20  WORD   starting sector no. (block dev.)
  444. ;
  445. ; Returns the Return Status word set appropriately, and
  446. ; Request Header + 18  WORD   actual bytes or sectors transferred
  447.  
  448. Outp_Vfy: 
  449.  
  450.         jmp     Done
  451.  
  452.         page
  453.  
  454. ;
  455. ; Function 10  Output Status
  456. ;
  457. ; Character devices only.
  458. ;
  459. ; Sets the Returned Status word:
  460. ; Done bit = 1
  461. ; Busy bit = 1 write request would wait for completion of
  462. ;              current request
  463. ;          = 0 device idle, write request would start immediately.
  464. ;
  465.  
  466. Outp_Stat:
  467.  
  468.         jmp     Done
  469.  
  470.         page
  471.  
  472. ;
  473. ; Function 11  Flush Output Buffers
  474. ; 
  475. ; Character devices only.
  476. ;
  477. ; Terminate pending requests.  The output buffer, if any,
  478. ; is emptied.
  479.  
  480. Outp_Flush:
  481.  
  482.         jmp     Done
  483.  
  484.         page
  485.  
  486. ;
  487. ; Function 12  I/O Control Write 
  488. ; 
  489. ; Only called if IOCTL bit in Device Header Attribute word is set.
  490. ;
  491. ; Called with
  492. ;
  493. ; Request Header + 13  BYTE   Media descriptor byte from DPB
  494. ; Request Header + 14  DWORD  Transfer address
  495. ; Request Header + 18  WORD   byte/sector count
  496. ; Request Header + 20  WORD   starting sector no. (block dev.)
  497. ;
  498. ; Returns the Return Status word set appropriately, and
  499. ; Request Header + 18  WORD   actual bytes or sectors transferred
  500. ;
  501. ; No error check is performed on IOCTL calls.
  502.  
  503. Ioctl_Outp:
  504.  
  505.         jmp     Done
  506.  
  507.         page
  508.  
  509. ;
  510. ; Function 13  Device Open
  511. ;
  512. ; MS-DOS version 3.0 and above only.
  513. ; Only called if OPEN/CLOSE/RM bit set in Attribute word.
  514. ; May be used to manage local buffering.  Reference count
  515. ; is incremented keeping track of number of open files on
  516. ; the device.  On character devices can be used to send
  517. ; device initialization string, which can be set by IOCTL 
  518. ; Write.  Note that CON AUX and PRN devices are always open.
  519. ;
  520. ; Returns the Return Status word set to "Done".
  521. ;
  522. Dev_Open:
  523.  
  524.         jmp     Done
  525.  
  526.         page
  527.  
  528. ;
  529. ; Function 14  Device Close
  530. ;
  531. ; MS-DOS version 3.0 and above only.
  532. ; Only called if OPEN/CLOSE/RM bit set in Attribute word.
  533. ; May be used to manage local buffering.  Reference count
  534. ; is decremented keeping track of number of open files on
  535. ; the device; when count reaches zero all files have been closed 
  536. ; and the driver should flush buffers as user may change disks.
  537. ; On character devices can be used to send device post-I/O
  538. ; string such as a form feed, which can be set by IOCTL 
  539. ; Write.  Note that CON AUX and PRN devices are never closed.
  540. ;
  541. ; Returns the Return Status word set to "Done".
  542. ;
  543. Dev_Close:
  544.  
  545.         jmp     Done
  546.  
  547.         page
  548.  
  549. ;
  550. ; Function 15  Removeable Media
  551. ;
  552. ; MS-DOS version 3.0 and above only.
  553. ; Only called if OPEN/CLOSE/RM bit set in Attribute word
  554. ;    and device type is block.
  555. ;
  556. ; Returns the Return Status word set to "Done" and 
  557. ; Busy bit = 1 if media is non-removable.  
  558. ;          = 0 if media is removable.
  559. ;
  560. Rem_Media:
  561.  
  562.         jmp     Done
  563.  
  564.  
  565.         page
  566.  
  567. ; This Initialization code for the driver is called only
  568. ; once when the driver is loaded.  It is responsible for
  569. ; initializing the hardware, setting up any necessary 
  570. ; interrupt vectors, and it must return the address
  571. ; of the first free memory after the driver to the BDOS.
  572. ; If it is a block device driver, Init must also return the 
  573. ; address of the Bios Parameter Block pointer array; if all 
  574. ; units are the same, all pointers can point to the same BPB.
  575. ; Only MS-DOS services 01-0CH and 30H can be called by the 
  576. ; Initialization function. 
  577. ;
  578. ; In this example, Init returns its own address to the DOS as 
  579. ; the start of free memory after the driver, so that the memory 
  580. ; occupied by INIT will be reclaimed after it is finished 
  581. ; with its work.  
  582. ;
  583. ; Called with:
  584. ;
  585. ; Request Header + 18  DWORD pointer to the character after the "="
  586. ;                            on the CONFIG.SYS line that loaded 
  587. ;                            driver; this information is read only.
  588. ;                  22  BYTE  drive letter for first unit of a 
  589. ;                            block driver (0=A 1=B etc)
  590. ;                            (MS-DOS 3.x only)   
  591. ;
  592. ; Returns:
  593. ; 
  594. ; Request Header + 13  BYTE  Number of units (block devices only)
  595. ;                + 14  DWORD address of first free memory above driver
  596. ;                + 18  DWORD BPB pointer array (block devices only)     
  597. ;
  598.  
  599. Init:                           ; Function 0
  600.                                 ; initialize device driver
  601.  
  602.         push    es              ; push Request Header addr
  603.         push    di
  604.  
  605.         mov     ah,9            ; print sign-on message
  606.         mov     dx,offset Ident
  607.         int     21h
  608.  
  609.         pop     di              ; restore Request Header addr
  610.         pop     es
  611.  
  612.                                 ; set first usable memory addr.
  613.         mov     word ptr es:[di.Address],offset Init
  614.         mov     word ptr es:[di.Address+2],cs
  615.  
  616.         jmp     Done
  617.  
  618.  
  619. Intr    endp
  620.  
  621.  
  622. Driver  endp
  623.  
  624. code    ends
  625.         
  626.         end     
  627. Capture buffer closed.
  628.  
  629. Press <CR> to continue: